home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / e / kyz_obj.lha / doc / cdplayer.doc < prev    next >
Text File  |  1998-10-18  |  19KB  |  663 lines
  1. TABLE OF CONTENTS
  2.  
  3. cdplayer.m/--overview--
  4. cdplayer.m/currenttrack
  5. cdplayer.m/discchanged
  6. cdplayer.m/discinserted
  7. cdplayer.m/eject
  8. cdplayer.m/ejected
  9. cdplayer.m/end
  10. cdplayer.m/insert
  11. cdplayer.m/length
  12. cdplayer.m/location
  13. cdplayer.m/maketime
  14. cdplayer.m/open
  15. cdplayer.m/pause
  16. cdplayer.m/paused
  17. cdplayer.m/play
  18. cdplayer.m/playing
  19. cdplayer.m/search
  20. cdplayer.m/spindown
  21. cdplayer.m/spinning
  22. cdplayer.m/spinup
  23. cdplayer.m/stop
  24. cdplayer.m/timeval
  25. cdplayer.m/trackinfo
  26. cdplayer.m/tracks
  27. cdplayer.m/unpause
  28. cdplayer.m/waitfordisc
  29. cdplayer.m/--overview--                               cdplayer.m/--overview--
  30.  
  31.    PURPOSE
  32.     To provide an interface to the cd.device for playing Audio CDs.
  33.  
  34.    OVERVIEW
  35.     This  object  simulates the high-level idea of 'CD Controls', such
  36.     as  play(),  pause(), stop() and so on. It also allows querying of
  37.     the  CD  drive, such as whether the door is open or if the disc is
  38.     spinning.
  39.     
  40.     Audio  play  is,  of  course,  asynchronous,  and the audio can be
  41.     manipulated while play is in progress.
  42.  
  43.     Construction and destruction:
  44.       open(), end()
  45.     
  46.     CD Controls:
  47.       play(), stop(), search()
  48.  
  49.     CD State controls:
  50.       pause(), unpause(), paused() - pause control
  51.       eject(), insert(), ejected() - door control
  52.       spinup(), spindown(), spinning() - motor control
  53.       playing(), location()
  54.  
  55.     Disc information:
  56.       discchanged(), discinserted(), waitfordisc()
  57.  
  58.     Track information:
  59.       length(), tracks(), trackinfo(), currenttrack()
  60.  
  61.     Timing specifications
  62.  
  63.         Audio CDs are marked in minutes, seconds and frames. There are
  64.         75 frames in a second, and 60 seconds in a minute.
  65.     
  66.         To work with Audio CDs, there must be some way of representing
  67.         a  time  values.  Time values are used to specify positions on
  68.         the  CD,  offsets  from the beginning of the CD or tracks, the
  69.         length of tracks, the total time on the CD, amounts of time to
  70.         be played, and so on.
  71.     
  72.         There  are two standard ways to represent time values for CDs.
  73.         One  is  called  'LSN  format',  where LSN stands for 'Logical
  74.         Sector  Numbers'.  LSN  format  is  basically a mass number of
  75.         frames,  where  a  minute  is  4500 frames, and a second is 75
  76.         frames.  The  advantage  of  this  format is that times can be
  77.         worked  with  like  normal numbers. You can add them, subtract
  78.         them and compare them with normal number math.
  79.     
  80.         The  other standard time representation is 'MSF format', where
  81.         MSF  stands  for  'Minutes,  Seconds,  Frames'. Just as an LSN
  82.         value  is  an unsigned 32-bit LONG value, so is an MSF value -
  83.         but  each  byte  of  the  LONG is used individually to store a
  84.         minute  count,  second  count,  and  a  frame  count. The most
  85.         significant  byte is unused, the next most significant byte is
  86.         a number from 0 to 255 representing the number of minutes, the
  87.         next  byte is a number from 0 to 59 representing the number of
  88.         seconds,  and  the least significant byte holds a value from -
  89.         to 74 containing a number of frames.
  90.     
  91.         A  fair  analogy for MSF format would be the well known Binary
  92.         Coded  Decimal  (BCD) format supported by most processors. The
  93.         numbers   cannot  be  added  or  manipulated  without  special
  94.         instructions,  and  'invalid'  values  are  possible,  but the
  95.         values  themselves  are  more  readable  and 'splittable' than
  96.         normal integers.
  97.     
  98.         Before an argument breaks out, it must be said that this class
  99.         always  uses  LSN format time values - in all instances. It is
  100.         far  more  practical  to  do  so  than  to support MSF format.
  101.         However,  there are two functions to provide the functionality
  102.         inherent  in  the MSF format. maketime() will take a number of
  103.         minutes,  seconds  and frames, and create an LSN format number
  104.         from  them.  timeval()  will  take  an  LSN format number, and
  105.         return a number of minutes, seconds and frames.
  106.  
  107.         The unit of time value measurement is referred to as 'frames'.
  108.     
  109.     Error handling
  110.  
  111.         When  the  functions of the cdplayer object mention 'failure',
  112.         'errors'  and  so  on,  they  refer to logical errors that the
  113.         functions specifically expect and report. However, they do not
  114.         expect  I/O  errors  with  the  CD  device.  If  the CD device
  115.         returns an errors, the exception CDPERR_DEVICE will be thrown,
  116.         and the device error will be in exceptioninfo. In their normal
  117.         operation,  the  functions  do  not cause or expect any device
  118.         errors. However, events beyond their control can cause them.
  119.         In practise, it is very difficult to cause them.
  120.  
  121. cdplayer.m/currenttrack                               cdplayer.m/currenttrack
  122.  
  123.    NAME
  124.        cdplayer.currenttrack() -- report track being played.
  125.  
  126.    SYNOPSIS
  127.        track := currenttrack()
  128.  
  129.    FUNCTION
  130.     Returns  the  latest known currently playing track. The CD must be
  131.     playing, but it does not matter if play is paused or searching.
  132.  
  133.    RESULT
  134.     track - CDTRACK_INVALID  if  the  CD is not playing, otherwise the
  135.             track number.
  136.  
  137.    SEE ALSO
  138.        play(), playing(), location()
  139.  
  140. cdplayer.m/discchanged                                 cdplayer.m/discchanged
  141.  
  142.    NAME
  143.     cdplayer.discchanged() -- report if disc has been changed.
  144.  
  145.    SYNOPSIS
  146.     changed := discchanged()
  147.  
  148.    FUNCTION
  149.     This function returns TRUE if the disc in the CD drive has changed
  150.     since  you last called this function. To help you, the function is
  151.     called  automatically  on  your  behalf  when you first create the
  152.     cdplayer object.
  153.  
  154.    RESULT
  155.     changed - TRUE if the disc in the CD drive has changed since this
  156.               function was last called, FALSE otherwise.
  157.  
  158.    NOTE
  159.     A disc change does not imply that there is a disc in the drive!
  160.  
  161.    SEE ALSO
  162.     discinserted(), waitfordisc()
  163.  
  164. cdplayer.m/discinserted                               cdplayer.m/discinserted
  165.  
  166.    NAME
  167.     cdplayer.discinserted() -- report if a disc is in the drive.
  168.  
  169.    SYNOPSIS
  170.     inserted := discinserted()
  171.  
  172.    FUNCTION
  173.     Reports if a readable disc is ready and in the CD drive.
  174.  
  175.    RESULT
  176.     inserted - TRUE if a disc is inserted, FALSE otherwise.
  177.  
  178.    NOTE
  179.     Discs  may  be  removed at any time, even just after this call has
  180.     returned TRUE! A TRUE result from this function is no guarantee of
  181.     permanent disc availability.
  182.  
  183.    SEE ALSO
  184.     discchanged(), waitfordisc()
  185.  
  186. cdplayer.m/eject                                             cdplayer.m/eject
  187.  
  188.    NAME
  189.     cdplayer.eject() -- open the CD drawer/door.
  190.  
  191.    SYNOPSIS
  192.     eject()
  193.  
  194.    FUNCTION
  195.     Requests the CD drive to open its drawer or door.
  196.  
  197.    NOTE
  198.     You  must have a CD drive with a motorized drawer or door for this
  199.        call to work. The CD³² drive throws IO error CDERR_NOCMD.
  200.  
  201.    SEE ALSO
  202.     insert(), ejected()
  203.  
  204. cdplayer.m/ejected                                         cdplayer.m/ejected
  205.  
  206.    NAME
  207.     cdplayer.ejected() -- report if CD drawer/door is open.
  208.  
  209.    SYNOPSIS
  210.     door_open := ejected()
  211.  
  212.    FUNCTION
  213.     Reports the current state of the CD drawer or door.
  214.  
  215.    RESULT
  216.     Returns TRUE if the door is open, FALSE otherwise.
  217.  
  218.    NOTE
  219.     Cartridge-based CD drives do not normally report being 'open'.
  220.  
  221.    SEE ALSO
  222.     eject(), insert()
  223.  
  224. cdplayer.m/end                                                 cdplayer.m/end
  225.  
  226.    NAME
  227.     cdplayer.end() -- Destructor.
  228.  
  229.    SYNOPSIS
  230.     end()
  231.  
  232.    FUNCTION
  233.     Frees resources used by an instance of the cdplayer class.
  234.  
  235.    SEE ALSO
  236.     new()
  237.  
  238. cdplayer.m/insert                                           cdplayer.m/insert
  239.  
  240.    NAME
  241.     cdplayer.insert() -- close the CD drawer/door.
  242.  
  243.    SYNOPSIS
  244.     insert()
  245.  
  246.    FUNCTION
  247.     Requests the CD drive to close its drawer or door.
  248.  
  249.    NOTE
  250.     You  must have a CD drive with a motorized drawer or door for this
  251.        call to work. The CD³² drive throws IO error CDERR_NOCMD.
  252.  
  253.    SEE ALSO
  254.     eject(), ejected()
  255.  
  256. cdplayer.m/length                                           cdplayer.m/length
  257.  
  258.    NAME
  259.     cdplayer.length() -- report the running time for the CD.
  260.  
  261.    SYNOPSIS
  262.     length := length()
  263.  
  264.    FUNCTION
  265.     Returns the length in time of the CD currently inserted.
  266.  
  267.    RESULT
  268.     length - A time value in frames, or CDTIME_INVALID in error.
  269.  
  270.    SEE ALSO
  271.     tracks()
  272.  
  273. cdplayer.m/location                                       cdplayer.m/location
  274.  
  275.    NAME
  276.